home *** CD-ROM | disk | FTP | other *** search
/ Spidla DivX / DivX.bin / FLAC 1.1.0 / include / FLAC / stream_decoder.h < prev    next >
Encoding:
C/C++ Source or Header  |  2003-01-01  |  32.5 KB  |  802 lines
  1. /* libFLAC - Free Lossless Audio Codec library
  2.  * Copyright (C) 2000,2001,2002,2003  Josh Coalson
  3.  *
  4.  * This library is free software; you can redistribute it and/or
  5.  * modify it under the terms of the GNU Library General Public
  6.  * License as published by the Free Software Foundation; either
  7.  * version 2 of the License, or (at your option) any later version.
  8.  *
  9.  * This library is distributed in the hope that it will be useful,
  10.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12.  * Library General Public License for more details.
  13.  *
  14.  * You should have received a copy of the GNU Library General Public
  15.  * License along with this library; if not, write to the
  16.  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17.  * Boston, MA  02111-1307, USA.
  18.  */
  19.  
  20. #ifndef FLAC__STREAM_DECODER_H
  21. #define FLAC__STREAM_DECODER_H
  22.  
  23. #include "export.h"
  24. #include "format.h"
  25.  
  26. #ifdef __cplusplus
  27. extern "C" {
  28. #endif
  29.  
  30.  
  31. /** \file include/FLAC/stream_decoder.h
  32.  *
  33.  *  \brief
  34.  *  This module contains the functions which implement the stream
  35.  *  decoder.
  36.  *
  37.  *  See the detailed documentation in the
  38.  *  \link flac_stream_decoder stream decoder \endlink module.
  39.  */
  40.  
  41. /** \defgroup flac_decoder FLAC/ *_decoder.h: decoder interfaces
  42.  *  \ingroup flac
  43.  *
  44.  *  \brief
  45.  *  This module describes the three decoder layers provided by libFLAC.
  46.  *
  47.  * For decoding FLAC streams, libFLAC provides three layers of access.  The
  48.  * lowest layer is non-seekable stream-level decoding, the next is seekable
  49.  * stream-level decoding, and the highest layer is file-level decoding.  The
  50.  * interfaces are described in the \link flac_stream_decoder stream decoder
  51.  * \endlink, \link flac_seekable_stream_decoder seekable stream decoder
  52.  * \endlink, and \link flac_file_decoder file decoder \endlink modules
  53.  * respectively.  Typically you will choose the highest layer that your input
  54.  * source will support.
  55.  *
  56.  * The stream decoder relies on callbacks for all input and output and has no
  57.  * provisions for seeking.  The seekable stream decoder wraps the stream
  58.  * decoder and exposes functions for seeking.  However, you must provide
  59.  * extra callbacks for seek-related operations on your stream, like seek and
  60.  * tell.  The file decoder wraps the seekable stream decoder and supplies
  61.  * most of the callbacks internally, simplifying the processing of standard
  62.  * files.
  63.  */
  64.  
  65. /** \defgroup flac_stream_decoder FLAC/stream_decoder.h: stream decoder interface
  66.  *  \ingroup flac_decoder
  67.  *
  68.  *  \brief
  69.  *  This module contains the functions which implement the stream
  70.  *  decoder.
  71.  *
  72.  * The basic usage of this decoder is as follows:
  73.  * - The program creates an instance of a decoder using
  74.  *   FLAC__stream_decoder_new().
  75.  * - The program overrides the default settings and sets callbacks for
  76.  *   reading, writing, error reporting, and metadata reporting using
  77.  *   FLAC__stream_decoder_set_*() functions.
  78.  * - The program initializes the instance to validate the settings and
  79.  *   prepare for decoding using FLAC__stream_decoder_init().
  80.  * - The program calls the FLAC__stream_decoder_process_*() functions
  81.  *   to decode data, which subsequently calls the callbacks.
  82.  * - The program finishes the decoding with FLAC__stream_decoder_finish(),
  83.  *   which flushes the input and output and resets the decoder to the
  84.  *   uninitialized state.
  85.  * - The instance may be used again or deleted with
  86.  *   FLAC__stream_decoder_delete().
  87.  *
  88.  * In more detail, the program will create a new instance by calling
  89.  * FLAC__stream_decoder_new(), then call FLAC__stream_decoder_set_*()
  90.  * functions to set the callbacks and client data, and call
  91.  * FLAC__stream_decoder_init().  The required callbacks are:
  92.  *
  93.  * - Read callback - This function will be called when the decoder needs
  94.  *   more input data.  The address of the buffer to be filled is supplied,
  95.  *   along with the number of bytes the buffer can hold.  The callback may
  96.  *   choose to supply less data and modify the byte count but must be careful
  97.  *   not to overflow the buffer.  The callback then returns a status code
  98.  *   chosen from FLAC__StreamDecoderReadStatus.
  99.  * - Write callback - This function will be called when the decoder has
  100.  *   decoded a single frame of data.  The decoder will pass the frame
  101.  *   metadata as well as an array of pointers (one for each channel)
  102.  *   pointing to the decoded audio.
  103.  * - Metadata callback - This function will be called when the decoder has
  104.  *   decoded a metadata block.  In a valid FLAC file there will always be
  105.  *   one STREAMINFO block, followed by zero or more other metadata
  106.  *   blocks.  These will be supplied by the decoder in the same order as
  107.  *   they appear in the stream and always before the first audio frame
  108.  *   (i.e. write callback).  The metadata block that is passed in must not
  109.  *   be modified, and it doesn't live beyond the callback, so you should
  110.  *   make a copy of it with FLAC__metadata_object_clone() if you will need
  111.  *   it elsewhere.  Since metadata blocks can potentially be large, by
  112.  *   default the decoder only calls the metadata callback for the STREAMINFO
  113.  *   block; you can instruct the decoder to pass or filter other blocks with
  114.  *   FLAC__stream_decoder_set_metadata_*() calls.
  115.  * - Error callback - This function will be called whenever an error occurs
  116.  *   during decoding.
  117.  *
  118.  * Once the decoder is initialized, your program will call one of several
  119.  * functions to start the decoding process:
  120.  *
  121.  * - FLAC__stream_decoder_process_single() - Tells the decoder to process at
  122.  *   most one metadata block or audio frame and return, calling either the
  123.  *   metadata callback or write callback, respectively, once.  If the decoder
  124.  *   loses sync it will return with only the error callback being called.
  125.  * - FLAC__stream_decoder_process_until_end_of_metadata() - Tells the decoder
  126.  *   to process the stream from the current location and stop upon reaching
  127.  *   the first audio frame.  The user will get one metadata, write, or error
  128.  *   callback per metadata block, audio frame, or sync error, respectively.
  129.  * - FLAC__stream_decoder_process_until_end_of_stream() - Tells the decoder
  130.  *   to process the stream from the current location until the read callback
  131.  *   returns FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM or
  132.  *   FLAC__STREAM_DECODER_READ_STATUS_ABORT.  The user will get one metadata,
  133.  *   write, or error callback per metadata block, audio frame, or sync error,
  134.  *   respectively.
  135.  *
  136.  * When the decoder has finished decoding (normally or through an abort),
  137.  * the instance is finished by calling FLAC__stream_decoder_finish(), which
  138.  * ensures the decoder is in the correct state and frees memory.  Then the
  139.  * instance may be deleted with FLAC__stream_decoder_delete() or initialized
  140.  * again to decode another stream.
  141.  *
  142.  * Note that the stream decoder has no real concept of stream position, it
  143.  * just converts data.  To seek within a stream the callbacks have only to
  144.  * flush the decoder using FLAC__stream_decoder_flush() and start feeding
  145.  * data from the new position through the read callback.  The seekable
  146.  * stream decoder does just this.
  147.  *
  148.  * The FLAC__stream_decoder_set_metadata_*() functions deserve special
  149.  * attention.  By default, the decoder only calls the metadata_callback for
  150.  * the STREAMINFO block.  These functions allow you to tell the decoder
  151.  * explicitly which blocks to parse and return via the metadata_callback
  152.  * and/or which to skip.  Use a FLAC__stream_decoder_set_metadata_respond_all(),
  153.  * FLAC__stream_decoder_set_metadata_ignore() ... or FLAC__stream_decoder_set_metadata_ignore_all(),
  154.  * FLAC__stream_decoder_set_metadata_respond() ... sequence to exactly specify which
  155.  * blocks to return.  Remember that some metadata blocks can be big so
  156.  * filtering out the ones you don't use can reduce the memory requirements
  157.  * of the decoder.  Also note the special forms
  158.  * FLAC__stream_decoder_set_metadata_respond_application(id) and
  159.  * FLAC__stream_decoder_set_metadata_ignore_application(id) for filtering APPLICATION
  160.  * blocks based on the application ID.
  161.  *
  162.  * STREAMINFO and SEEKTABLE blocks are always parsed and used internally, but
  163.  * they still can legally be filtered from the metadata_callback.
  164.  *
  165.  * \note
  166.  * The "set" functions may only be called when the decoder is in the
  167.  * state FLAC__STREAM_DECODER_UNINITIALIZED, i.e. after
  168.  * FLAC__stream_decoder_new() or FLAC__stream_decoder_finish(), but
  169.  * before FLAC__stream_decoder_init().  If this is the case they will
  170.  * return \c true, otherwise \c false.
  171.  *
  172.  * \note
  173.  * FLAC__stream_decoder_finish() resets all settings to the constructor
  174.  * defaults, including the callbacks.
  175.  *
  176.  * \{
  177.  */
  178.  
  179.  
  180. /** State values for a FLAC__StreamDecoder
  181.  *
  182.  *  The decoder's state can be obtained by calling FLAC__stream_decoder_get_state().
  183.  */
  184. typedef enum {
  185.  
  186.     FLAC__STREAM_DECODER_SEARCH_FOR_METADATA = 0,
  187.     /**< The decoder is ready to search for metadata. */
  188.  
  189.     FLAC__STREAM_DECODER_READ_METADATA,
  190.     /**< The decoder is ready to or is in the process of reading metadata. */
  191.  
  192.     FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC,
  193.     /**< The decoder is ready to or is in the process of searching for the frame sync code. */
  194.  
  195.     FLAC__STREAM_DECODER_READ_FRAME,
  196.     /**< The decoder is ready to or is in the process of reading a frame. */
  197.  
  198.     FLAC__STREAM_DECODER_END_OF_STREAM,
  199.     /**< The decoder has reached the end of the stream. */
  200.  
  201.     FLAC__STREAM_DECODER_ABORTED,
  202.     /**< The decoder was aborted by the read callback. */
  203.  
  204.     FLAC__STREAM_DECODER_UNPARSEABLE_STREAM,
  205.     /**< The decoder encountered reserved fields in use in the stream. */
  206.  
  207.     FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
  208.     /**< An error occurred allocating memory. */
  209.  
  210.     FLAC__STREAM_DECODER_ALREADY_INITIALIZED,
  211.     /**< FLAC__stream_decoder_init() was called when the decoder was
  212.      * already initialized, usually because
  213.      * FLAC__stream_decoder_finish() was not called.
  214.      */
  215.  
  216.     FLAC__STREAM_DECODER_INVALID_CALLBACK,
  217.     /**< FLAC__stream_decoder_init() was called without all callbacks being set. */
  218.  
  219.     FLAC__STREAM_DECODER_UNINITIALIZED
  220.     /**< The decoder is in the uninitialized state. */
  221.  
  222. } FLAC__StreamDecoderState;
  223.  
  224. /** Maps a FLAC__StreamDecoderState to a C string.
  225.  *
  226.  *  Using a FLAC__StreamDecoderState as the index to this array
  227.  *  will give the string equivalent.  The contents should not be modified.
  228.  */
  229. extern FLAC_API const char * const FLAC__StreamDecoderStateString[];
  230.  
  231.  
  232. /** Return values for the FLAC__StreamDecoder read callback.
  233.  */
  234. typedef enum {
  235.  
  236.     FLAC__STREAM_DECODER_READ_STATUS_CONTINUE,
  237.     /**< The read was OK and decoding can continue. */
  238.  
  239.     FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM,
  240.     /**< The read was attempted at the end of the stream. */
  241.  
  242.     FLAC__STREAM_DECODER_READ_STATUS_ABORT
  243.     /**< An unrecoverable error occurred.  The decoder will return from the process call. */
  244.  
  245. } FLAC__StreamDecoderReadStatus;
  246.  
  247. /** Maps a FLAC__StreamDecoderReadStatus to a C string.
  248.  *
  249.  *  Using a FLAC__StreamDecoderReadStatus as the index to this array
  250.  *  will give the string equivalent.  The contents should not be modified.
  251.  */
  252. extern FLAC_API const char * const FLAC__StreamDecoderReadStatusString[];
  253.  
  254.  
  255. /** Return values for the FLAC__StreamDecoder write callback.
  256.  */
  257. typedef enum {
  258.  
  259.     FLAC__STREAM_DECODER_WRITE_STATUS_CONTINUE,
  260.     /**< The write was OK and decoding can continue. */
  261.  
  262.     FLAC__STREAM_DECODER_WRITE_STATUS_ABORT
  263.     /**< An unrecoverable error occurred.  The decoder will return from the process call. */
  264.  
  265. } FLAC__StreamDecoderWriteStatus;
  266.  
  267. /** Maps a FLAC__StreamDecoderWriteStatus to a C string.
  268.  *
  269.  *  Using a FLAC__StreamDecoderWriteStatus as the index to this array
  270.  *  will give the string equivalent.  The contents should not be modified.
  271.  */
  272. extern FLAC_API const char * const FLAC__StreamDecoderWriteStatusString[];
  273.  
  274.  
  275. /** Possible values passed in to the FLAC__StreamDecoder error callback.
  276.  */
  277. typedef enum {
  278.  
  279.     FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC,
  280.     /**< An error in the stream caused the decoder to lose synchronization. */
  281.  
  282.     FLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER,
  283.     /**< The decoder encountered a corrupted frame header. */
  284.  
  285.     FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH
  286.     /**< The frame's data did not match the CRC in the footer. */
  287.  
  288. } FLAC__StreamDecoderErrorStatus;
  289.  
  290. /** Maps a FLAC__StreamDecoderErrorStatus to a C string.
  291.  *
  292.  *  Using a FLAC__StreamDecoderErrorStatus as the index to this array
  293.  *  will give the string equivalent.  The contents should not be modified.
  294.  */
  295. extern FLAC_API const char * const FLAC__StreamDecoderErrorStatusString[];
  296.  
  297.  
  298. /***********************************************************************
  299.  *
  300.  * class FLAC__StreamDecoder
  301.  *
  302.  ***********************************************************************/
  303.  
  304. struct FLAC__StreamDecoderProtected;
  305. struct FLAC__StreamDecoderPrivate;
  306. /** The opaque structure definition for the stream decoder type.
  307.  *  See the \link flac_stream_decoder stream decoder module \endlink
  308.  *  for a detailed description.
  309.  */
  310. typedef struct {
  311.     struct FLAC__StreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
  312.     struct FLAC__StreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
  313. } FLAC__StreamDecoder;
  314.  
  315. /** Signature for the read callback.
  316.  *  See FLAC__stream_decoder_set_read_callback() for more info.
  317.  *
  318.  * \param  decoder  The decoder instance calling the callback.
  319.  * \param  buffer   A pointer to a location for the callee to store
  320.  *                  data to be decoded.
  321.  * \param  bytes    A pointer to the size of the buffer.  On entry
  322.  *                  to the callback, it contains the maximum number
  323.  *                  of bytes that may be stored in \a buffer.  The
  324.  *                  callee must set it to the actual number of bytes
  325.  *                  stored before returning.
  326.  * \param  client_data  The callee's client data set through
  327.  *                      FLAC__stream_decoder_set_client_data().
  328.  * \retval FLAC__StreamDecoderReadStatus
  329.  *    The callee's return status.
  330.  */
  331. typedef FLAC__StreamDecoderReadStatus (*FLAC__StreamDecoderReadCallback)(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
  332.  
  333. /** Signature for the write callback.
  334.  *  See FLAC__stream_decoder_set_write_callback() for more info.
  335.  *
  336.  * \param  decoder  The decoder instance calling the callback.
  337.  * \param  frame    The description of the decoded frame.  See
  338.  *                  FLAC__Frame.
  339.  * \param  buffer   An array of pointers to decoded channels of data.
  340.  *                  Each pointer will point to an array of signed
  341.  *                  samples of length \a frame->header.blocksize.
  342.  *                  Currently, the channel order has no meaning
  343.  *                  except for stereo streams; in this case channel
  344.  *                  0 is left and 1 is right.
  345.  * \param  client_data  The callee's client data set through
  346.  *                      FLAC__stream_decoder_set_client_data().
  347.  * \retval FLAC__StreamDecoderWriteStatus
  348.  *    The callee's return status.
  349.  */
  350. typedef FLAC__StreamDecoderWriteStatus (*FLAC__StreamDecoderWriteCallback)(const FLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
  351.  
  352. /** Signature for the metadata callback.
  353.  *  See FLAC__stream_decoder_set_metadata_callback() for more info.
  354.  *
  355.  * \param  decoder  The decoder instance calling the callback.
  356.  * \param  metadata The decoded metadata block.
  357.  * \param  client_data  The callee's client data set through
  358.  *                      FLAC__stream_decoder_set_client_data().
  359.  */
  360. typedef void (*FLAC__StreamDecoderMetadataCallback)(const FLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
  361.  
  362. /** Signature for the error callback.
  363.  *  See FLAC__stream_decoder_set_error_callback() for more info.
  364.  *
  365.  * \param  decoder  The decoder instance calling the callback.
  366.  * \param  status   The error encountered by the decoder.
  367.  * \param  client_data  The callee's client data set through
  368.  *                      FLAC__stream_decoder_set_client_data().
  369.  */
  370. typedef void (*FLAC__StreamDecoderErrorCallback)(const FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
  371.  
  372.  
  373. /***********************************************************************
  374.  *
  375.  * Class constructor/destructor
  376.  *
  377.  ***********************************************************************/
  378.  
  379. /** Create a new stream decoder instance.  The instance is created with
  380.  *  default settings; see the individual FLAC__stream_decoder_set_*()
  381.  *  functions for each setting's default.
  382.  *
  383.  * \retval FLAC__StreamDecoder*
  384.  *    \c NULL if there was an error allocating memory, else the new instance.
  385.  */
  386. FLAC_API FLAC__StreamDecoder *FLAC__stream_decoder_new();
  387.  
  388. /** Free a decoder instance.  Deletes the object pointed to by \a decoder.
  389.  *
  390.  * \param decoder  A pointer to an existing decoder.
  391.  * \assert
  392.  *    \code decoder != NULL \endcode
  393.  */
  394. FLAC_API void FLAC__stream_decoder_delete(FLAC__StreamDecoder *decoder);
  395.  
  396.  
  397. /***********************************************************************
  398.  *
  399.  * Public class method prototypes
  400.  *
  401.  ***********************************************************************/
  402.  
  403. /** Set the read callback.
  404.  *  The supplied function will be called when the decoder needs more input
  405.  *  data.  The address of the buffer to be filled is supplied, along with
  406.  *  the number of bytes the buffer can hold.  The callback may choose to
  407.  *  supply less data and modify the byte count but must be careful not to
  408.  *  overflow the buffer.  The callback then returns a status code chosen
  409.  *  from FLAC__StreamDecoderReadStatus.
  410.  *
  411.  * \note
  412.  * The callback is mandatory and must be set before initialization.
  413.  *
  414.  * \default \c NULL
  415.  * \param  decoder  A decoder instance to set.
  416.  * \param  value    See above.
  417.  * \assert
  418.  *    \code decoder != NULL \endcode
  419.  *    \code value != NULL \endcode
  420.  * \retval FLAC__bool
  421.  *    \c false if the decoder is already initialized, else \c true.
  422.  */
  423. FLAC_API FLAC__bool FLAC__stream_decoder_set_read_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderReadCallback value);
  424.  
  425. /** Set the write callback.
  426.  *  The supplied function will be called when the decoder has decoded a
  427.  *  single frame of data.  The decoder will pass the frame metadata as
  428.  *  well as an array of pointers (one for each channel) pointing to the
  429.  *  decoded audio.
  430.  *
  431.  * \note
  432.  * The callback is mandatory and must be set before initialization.
  433.  *
  434.  * \default \c NULL
  435.  * \param  decoder  A decoder instance to set.
  436.  * \param  value    See above.
  437.  * \assert
  438.  *    \code decoder != NULL \endcode
  439.  *    \code value != NULL \endcode
  440.  * \retval FLAC__bool
  441.  *    \c false if the decoder is already initialized, else \c true.
  442.  */
  443. FLAC_API FLAC__bool FLAC__stream_decoder_set_write_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderWriteCallback value);
  444.  
  445. /** Set the metadata callback.
  446.  *  The supplied function will be called when the decoder has decoded a metadata
  447.  *  block.  In a valid FLAC file there will always be one STREAMINFO block,
  448.  *  followed by zero or more other metadata blocks.  These will be supplied
  449.  *  by the decoder in the same order as they appear in the stream and always
  450.  *  before the first audio frame (i.e. write callback).  The metadata block
  451.  *  that is passed in must not be modified, and it doesn't live beyond the
  452.  *  callback, so you should make a copy of it with
  453.  *  FLAC__metadata_object_clone() if you will need it elsewhere.  Since
  454.  *  metadata blocks can potentially be large, by default the decoder only
  455.  *  calls the metadata callback for the STREAMINFO block; you can instruct
  456.  *  the decoder to pass or filter other blocks with
  457.  *  FLAC__stream_decoder_set_metadata_*() calls.
  458.  *
  459.  * \note
  460.  * The callback is mandatory and must be set before initialization.
  461.  *
  462.  * \default \c NULL
  463.  * \param  decoder  A decoder instance to set.
  464.  * \param  value    See above.
  465.  * \assert
  466.  *    \code decoder != NULL \endcode
  467.  *    \code value != NULL \endcode
  468.  * \retval FLAC__bool
  469.  *    \c false if the decoder is already initialized, else \c true.
  470.  */
  471. FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderMetadataCallback value);
  472.  
  473. /** Set the error callback.
  474.  *  The supplied function will be called whenever an error occurs during
  475.  *  decoding.
  476.  *
  477.  * \note
  478.  * The callback is mandatory and must be set before initialization.
  479.  *
  480.  * \default \c NULL
  481.  * \param  decoder  A decoder instance to set.
  482.  * \param  value    See above.
  483.  * \assert
  484.  *    \code decoder != NULL \endcode
  485.  *    \code value != NULL \endcode
  486.  * \retval FLAC__bool
  487.  *    \c false if the decoder is already initialized, else \c true.
  488.  */
  489. FLAC_API FLAC__bool FLAC__stream_decoder_set_error_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorCallback value);
  490.  
  491. /** Set the client data to be passed back to callbacks.
  492.  *  This value will be supplied to callbacks in their \a client_data
  493.  *  argument.
  494.  *
  495.  * \default \c NULL
  496.  * \param  decoder  A decoder instance to set.
  497.  * \param  value    See above.
  498.  * \assert
  499.  *    \code decoder != NULL \endcode
  500.  * \retval FLAC__bool
  501.  *    \c false if the decoder is already initialized, else \c true.
  502.  */
  503. FLAC_API FLAC__bool FLAC__stream_decoder_set_client_data(FLAC__StreamDecoder *decoder, void *value);
  504.  
  505. /** Direct the decoder to pass on all metadata blocks of type \a type.
  506.  *
  507.  * \default By default, only the \c STREAMINFO block is returned via the
  508.  *          metadata callback.
  509.  * \param  decoder  A decoder instance to set.
  510.  * \param  type     See above.
  511.  * \assert
  512.  *    \code decoder != NULL \endcode
  513.  *    \a type is valid
  514.  * \retval FLAC__bool
  515.  *    \c false if the decoder is already initialized, else \c true.
  516.  */
  517. FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond(FLAC__StreamDecoder *decoder, FLAC__MetadataType type);
  518.  
  519. /** Direct the decoder to pass on all APPLICATION metadata blocks of the
  520.  *  given \a id.
  521.  *
  522.  * \default By default, only the \c STREAMINFO block is returned via the
  523.  *          metadata callback.
  524.  * \param  decoder  A decoder instance to set.
  525.  * \param  id       See above.
  526.  * \assert
  527.  *    \code decoder != NULL \endcode
  528.  *    \code id != NULL \endcode
  529.  * \retval FLAC__bool
  530.  *    \c false if the decoder is already initialized, else \c true.
  531.  */
  532. FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
  533.  
  534. /** Direct the decoder to pass on all metadata blocks of any type.
  535.  *
  536.  * \default By default, only the \c STREAMINFO block is returned via the
  537.  *          metadata callback.
  538.  * \param  decoder  A decoder instance to set.
  539.  * \assert
  540.  *    \code decoder != NULL \endcode
  541.  * \retval FLAC__bool
  542.  *    \c false if the decoder is already initialized, else \c true.
  543.  */
  544. FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_respond_all(FLAC__StreamDecoder *decoder);
  545.  
  546. /** Direct the decoder to filter out all metadata blocks of type \a type.
  547.  *
  548.  * \default By default, only the \c STREAMINFO block is returned via the
  549.  *          metadata callback.
  550.  * \param  decoder  A decoder instance to set.
  551.  * \param  type     See above.
  552.  * \assert
  553.  *    \code decoder != NULL \endcode
  554.  *    \a type is valid
  555.  * \retval FLAC__bool
  556.  *    \c false if the decoder is already initialized, else \c true.
  557.  */
  558. FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore(FLAC__StreamDecoder *decoder, FLAC__MetadataType type);
  559.  
  560. /** Direct the decoder to filter out all APPLICATION metadata blocks of
  561.  *  the given \a id.
  562.  *
  563.  * \default By default, only the \c STREAMINFO block is returned via the
  564.  *          metadata callback.
  565.  * \param  decoder  A decoder instance to set.
  566.  * \param  id       See above.
  567.  * \assert
  568.  *    \code decoder != NULL \endcode
  569.  *    \code id != NULL \endcode
  570.  * \retval FLAC__bool
  571.  *    \c false if the decoder is already initialized, else \c true.
  572.  */
  573. FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore_application(FLAC__StreamDecoder *decoder, const FLAC__byte id[4]);
  574.  
  575. /** Direct the decoder to filter out all metadata blocks of any type.
  576.  *
  577.  * \default By default, only the \c STREAMINFO block is returned via the
  578.  *          metadata callback.
  579.  * \param  decoder  A decoder instance to set.
  580.  * \assert
  581.  *    \code decoder != NULL \endcode
  582.  * \retval FLAC__bool
  583.  *    \c false if the decoder is already initialized, else \c true.
  584.  */
  585. FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_ignore_all(FLAC__StreamDecoder *decoder);
  586.  
  587. /** Get the current decoder state.
  588.  *
  589.  * \param  decoder  A decoder instance to query.
  590.  * \assert
  591.  *    \code decoder != NULL \endcode
  592.  * \retval FLAC__StreamDecoderState
  593.  *    The current decoder state.
  594.  */
  595. FLAC_API FLAC__StreamDecoderState FLAC__stream_decoder_get_state(const FLAC__StreamDecoder *decoder);
  596.  
  597. /** Get the current number of channels in the stream being decoded.
  598.  *  Will only be valid after decoding has started and will contain the
  599.  *  value from the most recently decoded frame header.
  600.  *
  601.  * \param  decoder  A decoder instance to query.
  602.  * \assert
  603.  *    \code decoder != NULL \endcode
  604.  * \retval unsigned
  605.  *    See above.
  606.  */
  607. FLAC_API unsigned FLAC__stream_decoder_get_channels(const FLAC__StreamDecoder *decoder);
  608.  
  609. /** Get the current channel assignment in the stream being decoded.
  610.  *  Will only be valid after decoding has started and will contain the
  611.  *  value from the most recently decoded frame header.
  612.  *
  613.  * \param  decoder  A decoder instance to query.
  614.  * \assert
  615.  *    \code decoder != NULL \endcode
  616.  * \retval FLAC__ChannelAssignment
  617.  *    See above.
  618.  */
  619. FLAC_API FLAC__ChannelAssignment FLAC__stream_decoder_get_channel_assignment(const FLAC__StreamDecoder *decoder);
  620.  
  621. /** Get the current sample resolution in the stream being decoded.
  622.  *  Will only be valid after decoding has started and will contain the
  623.  *  value from the most recently decoded frame header.
  624.  *
  625.  * \param  decoder  A decoder instance to query.
  626.  * \assert
  627.  *    \code decoder != NULL \endcode
  628.  * \retval unsigned
  629.  *    See above.
  630.  */
  631. FLAC_API unsigned FLAC__stream_decoder_get_bits_per_sample(const FLAC__StreamDecoder *decoder);
  632.  
  633. /** Get the current sample rate in Hz of the stream being decoded.
  634.  *  Will only be valid after decoding has started and will contain the
  635.  *  value from the most recently decoded frame header.
  636.  *
  637.  * \param  decoder  A decoder instance to query.
  638.  * \assert
  639.  *    \code decoder != NULL \endcode
  640.  * \retval unsigned
  641.  *    See above.
  642.  */
  643. FLAC_API unsigned FLAC__stream_decoder_get_sample_rate(const FLAC__StreamDecoder *decoder);
  644.  
  645. /** Get the current blocksize of the stream being decoded.
  646.  *  Will only be valid after decoding has started and will contain the
  647.  *  value from the most recently decoded frame header.
  648.  *
  649.  * \param  decoder  A decoder instance to query.
  650.  * \assert
  651.  *    \code decoder != NULL \endcode
  652.  * \retval unsigned
  653.  *    See above.
  654.  */
  655. FLAC_API unsigned FLAC__stream_decoder_get_blocksize(const FLAC__StreamDecoder *decoder);
  656.  
  657. /** Initialize the decoder instance.
  658.  *  Should be called after FLAC__stream_decoder_new() and
  659.  *  FLAC__stream_decoder_set_*() but before any of the
  660.  *  FLAC__stream_decoder_process_*() functions.  Will set and return the
  661.  *  decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
  662.  *  if initialization succeeded.
  663.  *
  664.  * \param  decoder  An uninitialized decoder instance.
  665.  * \assert
  666.  *    \code decoder != NULL \endcode
  667.  * \retval FLAC__StreamDecoderState
  668.  *    \c FLAC__STREAM_DECODER_SEARCH_FOR_MEATADATA if initialization was
  669.  *    successful; see FLAC__StreamDecoderState for the meanings of other
  670.  *    return values.
  671.  */
  672. FLAC_API FLAC__StreamDecoderState FLAC__stream_decoder_init(FLAC__StreamDecoder *decoder);
  673.  
  674. /** Finish the decoding process.
  675.  *  Flushes the decoding buffer, releases resources, resets the decoder
  676.  *  settings to their defaults, and returns the decoder state to
  677.  *  FLAC__STREAM_DECODER_UNINITIALIZED.
  678.  *
  679.  *  In the event of a prematurely-terminated decode, it is not strictly
  680.  *  necessary to call this immediately before FLAC__stream_decoder_delete()
  681.  *  but it is good practice to match every FLAC__stream_decoder_init()
  682.  *  with a FLAC__stream_decoder_finish().
  683.  *
  684.  * \param  decoder  An uninitialized decoder instance.
  685.  * \assert
  686.  *    \code decoder != NULL \endcode
  687.  */
  688. FLAC_API void FLAC__stream_decoder_finish(FLAC__StreamDecoder *decoder);
  689.  
  690. /** Flush the stream input.
  691.  *  The decoder's input buffer will be cleared and the state set to
  692.  *  \c FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC.
  693.  *
  694.  * \param  decoder  A decoder instance.
  695.  * \assert
  696.  *    \code decoder != NULL \endcode
  697.  * \retval FLAC__bool
  698.  *    \c true if successful, else \c false if a memory allocation
  699.  *    error occurs.
  700.  */
  701. FLAC_API FLAC__bool FLAC__stream_decoder_flush(FLAC__StreamDecoder *decoder);
  702.  
  703. /** Reset the decoding process.
  704.  *  The decoder's input buffer will be cleared and the state set to
  705.  *  \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA.  This is similar to
  706.  *  FLAC__stream_decoder_finish() except that the settings are
  707.  *  preserved; there is no need to call FLAC__stream_decoder_init()
  708.  *  before decoding again.
  709.  *
  710.  * \param  decoder  A decoder instance.
  711.  * \assert
  712.  *    \code decoder != NULL \endcode
  713.  * \retval FLAC__bool
  714.  *    \c true if successful, else \c false if a memory allocation
  715.  *    error occurs.
  716.  */
  717. FLAC_API FLAC__bool FLAC__stream_decoder_reset(FLAC__StreamDecoder *decoder);
  718.  
  719. /** Decode one metadata block or audio frame.
  720.  *  This version instructs the decoder to decode a either a single metadata
  721.  *  block or a single frame and stop, unless the callbacks return a fatal
  722.  *  error or the read callback returns
  723.  *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
  724.  *
  725.  *  As the decoder needs more input it will call the read callback.
  726.  *  Depending on what was decoded, the metadata or write callback will be
  727.  *  called with the decoded metadata block or audio frame, unless an error
  728.  *  occurred.  If the decoder loses sync it will call the error callback
  729.  *  instead.
  730.  *
  731.  * \param  decoder  An initialized decoder instance in the state
  732.  *                  \c FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC.
  733.  * \assert
  734.  *    \code decoder != NULL \endcode
  735.  *    \code FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC \endcode
  736.  * \retval FLAC__bool
  737.  *    \c false if any read or write error occurred (except
  738.  *    \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
  739.  *    in any case, check the decoder state with
  740.  *    FLAC__stream_decoder_get_state() to see what went wrong or to
  741.  *    check for lost synchronization (a sign of stream corruption).
  742.  */
  743. FLAC_API FLAC__bool FLAC__stream_decoder_process_single(FLAC__StreamDecoder *decoder);
  744.  
  745. /** Decode until the end of the metadata.
  746.  *  This version instructs the decoder to decode from the current position
  747.  *  and continue until all the metadata has been read, or until the
  748.  *  callbacks return a fatal error or the read callback returns
  749.  *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
  750.  *
  751.  *  As the decoder needs more input it will call the read callback.
  752.  *  As each metadata block is decoded, the metadata callback will be called
  753.  *  with the decoded metadata.  If the decoder loses sync it will call the
  754.  *  error callback.
  755.  *
  756.  * \param  decoder  An initialized decoder instance in the state
  757.  *                  \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA.
  758.  * \assert
  759.  *    \code decoder != NULL \endcode
  760.  *    \code FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_METADATA \endcode
  761.  * \retval FLAC__bool
  762.  *    \c false if any read or write error occurred (except
  763.  *    \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
  764.  *    in any case, check the decoder state with
  765.  *    FLAC__stream_decoder_get_state() to see what went wrong or to
  766.  *    check for lost synchronization (a sign of stream corruption).
  767.  */
  768. FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_metadata(FLAC__StreamDecoder *decoder);
  769.  
  770. /** Decode until the end of the stream.
  771.  *  This version instructs the decoder to decode from the current position
  772.  *  and continue until the end of stream (the read callback returns
  773.  *  \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM), or until the
  774.  *  callbacks return a fatal error.
  775.  *
  776.  *  As the decoder needs more input it will call the read callback.
  777.  *  As each metadata block and frame is decoded, the metadata or write
  778.  *  callback will be called with the decoded metadata or frame.  If the
  779.  *  decoder loses sync it will call the error callback.
  780.  *
  781.  * \param  decoder  An initialized decoder instance in the state
  782.  *                  \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA.
  783.  * \assert
  784.  *    \code decoder != NULL \endcode
  785.  *    \code FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_METADATA \endcode
  786.  * \retval FLAC__bool
  787.  *    \c false if any read or write error occurred (except
  788.  *    \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
  789.  *    in any case, check the decoder state with
  790.  *    FLAC__stream_decoder_get_state() to see what went wrong or to
  791.  *    check for lost synchronization (a sign of stream corruption).
  792.  */
  793. FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_stream(FLAC__StreamDecoder *decoder);
  794.  
  795. /* \} */
  796.  
  797. #ifdef __cplusplus
  798. }
  799. #endif
  800.  
  801. #endif
  802.